DOC-7104: Migrate content/operate/rs/7.4/references/ (incl. rest-api) to render hooks - #4094
Conversation
… to render hooks
Unit 10 of 15: converts the frozen 7.4 references tree (246 files, 167
carrying relref/callout shortcodes) from {{< relref >}} and
{{< note >}}/{{< warning >}} shortcodes to plain markdown links and
> [!NOTE]/> [!WARNING] blockquotes resolved by the DOC-6909 render hooks.
The rest-api/ subtree (169 of the 246 files) is explicitly in scope per
the ticket: it was generated once when 7.4 was frozen and never
regenerated since, so a one-time conversion is safe and permanent.
Real counts (re-measured by grep, not taken from the ticket estimate):
1029 relref shortcodes across 165 files, 20 callouts (16 note, 4 warning,
0 tip/info/alert) across 16 files; 14 files carried both. Post-conversion
grep confirms 0 remaining shortcode-form relref/callout instances except
one pre-existing defect (see below), and 167/246 files touched overall.
One gotcha instance found and hand-fixed: cli-utilities/rladmin/_index.md
had a {{<note>}} indented inside a numbered list item, with only the
header line indented and the continuation/closing lines flush left (the
known converter limitation), plus a stray whitespace-only `>` artifact
line left by the closing tag's indentation. Fixed by re-indenting all
blockquote lines to match the list item and dropping the stray line;
verified via rendered HTML that the <li> nesting is unchanged before/after
(alert div closes inside the same <li>, immediately before </ol>, in both
builds).
Flagging, not fixing, a pre-existing defect: cli-utilities/redis-cli/_index.md
line 153 has `[Redis commands reference]({{< relref "/commands/" >}}` with
no closing `)` -- the link was already malformed before this migration
(confirmed via `git show HEAD` on the original), so the relref-to-plain
regex correctly left it unconverted rather than guessing. Left as-is per
"a missed rewrite is fine, a wrong one is not" and the AGENTS.md rule to
flag technical defects rather than silently fix them.
No relref-missing-slash instances found in this unit.
Verification: full-site hugo builds before/after (non-minified -- see
below), diffed with the DOC-7104-diff-hrefs-fix build/diff_rendered_hrefs.py
scoped to operate/rs/7.4/references: 244/244 pages compared, 0 href-set
changes. The verification-only patched diff script was staged from
origin/DOC-7104-diff-hrefs-fix, then unstaged and reverted before this
commit; build/diff_rendered_hrefs.py carries no changes here.
Build note: `hugo --minify` currently fails site-wide on this checkout with
a pre-existing esbuild syntax error while minifying a script on
/commands/cf.reserve, unrelated to this unit's path (confirmed pre-existing
in unit 8). Verification builds ran without --minify; both before and after
used identical flags, and rendered hrefs are unaffected by minification, so
the comparison is still valid.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…x.md The unit-10 subagent correctly left this pre-existing malformed relref (missing its closing paren) unconverted rather than guessing at a fix, per the migration script's by-design behavior. Fixing it here so this unit doesn't leave one relref shortcode behind in an otherwise fully converted file, matching the pattern already applied in units 1 and 2. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
dwdougherty
left a comment
There was a problem hiding this comment.
A few things to check...
| --- | ||
|
|
||
| The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands]({{< relref "/commands" >}}) directly from the command-line terminal or with [interactive mode](#interactive-mode). | ||
| The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode). |
There was a problem hiding this comment.
Bad link. Suggestion is questionable.
| The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode). | |
| The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands](/content/commands) directly from the command-line terminal or with [interactive mode](#interactive-mode). |
| - [Redis CLI documentation]({{< relref "/develop/tools/cli" >}}) | ||
| - [Redis commands reference]({{< relref "/commands/" >}} | ||
| - [Redis CLI documentation](/content/develop/tools/cli.md) | ||
| - [Redis commands reference](/commands/) |
| --- | ||
|
|
||
| The following tables show which Redis Open Source [connection management commands]({{< relref "/commands" >}}?group=connection) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following tables show which Redis Open Source [connection management commands](/commands?group=connection) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| --- | ||
|
|
||
| The following table shows which Redis Open Source [pub/sub commands]({{< relref "/commands" >}}?group=pubsub) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following table shows which Redis Open Source [pub/sub commands](/commands?group=pubsub) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| --- | ||
|
|
||
| The following table shows which Redis Open Source [scripting and function commands]({{< relref "/commands" >}}?group=scripting) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following table shows which Redis Open Source [scripting and function commands](/commands?group=scripting) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| --- | ||
|
|
||
| The following tables show which Redis Open Source [server management commands]({{< relref "/commands" >}}?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following tables show which Redis Open Source [server management commands](/commands?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| --- | ||
|
|
||
| The following table shows which Redis Open Source [transaction commands]({{< relref "/commands" >}}?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. | ||
| The following table shows which Redis Open Source [transaction commands](/commands?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. |
| | Method | Path | Description | | ||
| |--------|------|-------------| | ||
| | [PUT]({{< relref "./backup_reset_status#put-bdbs-actions-backup-reset-status" >}}) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status | | ||
| | [PUT](./backup_reset_status#put-bdbs-actions-backup-reset-status) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status | |
There was a problem hiding this comment.
Bunch of bad/questionable links on this whole page.
| | [GET](./all#get-all-debuginfo) | `/v1/debuginfo/all` | Gets debug info for all nodes | | ||
| | [GET](./all/bdb#get-all-debuginfo-bdb) | `/v1/debuginfo/all/bdb/{bdb_uid}` | Gets debug info for a database from all nodes | | ||
|
|
||
| ## Get debug info for the current node | ||
|
|
||
| | Method | Path | Description | | ||
| |--------|------|-------------| | ||
| | [GET]({{< relref "./node#get-debuginfo-node" >}}) | `/v1/debuginfo/node` | Gets debug info for the current node | | ||
| | [GET]({{< relref "./node/bdb#get-debuginfo-node-bdb" >}}) | `/v1/debuginfo/node/bdb/{bdb_uid}` | Gets debug info for a database from the current node | | ||
| | [GET](./node#get-debuginfo-node) | `/v1/debuginfo/node` | Gets debug info for the current node | | ||
| | [GET](./node/bdb#get-debuginfo-node-bdb) | `/v1/debuginfo/node/bdb/{bdb_uid}` | Gets debug info for a database from the current node | |
There was a problem hiding this comment.
Questionable links here.
…(same fix as #4093 review) Same defect pattern found and fixed on PR #4093 (7.22/references) after human review: 7 bare /commands?group=<x> links in compatibility/commands/ missing the /content/ prefix, and 10 source-relative relrefs in rest-api/requests/{bdbs/actions,debuginfo}/_index.md pointing at a directory/file with no extension (works via Hugo's render-link.html GetPage resolution, confirmed byte-identical rendered href before/after, but not a working link when the same markdown renders in GitHub's PR view or VS Code). This version snapshot is a near-identical copy of 7.22's rest-api tree, so the same instances recur in the same two files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Proactively applied the identical fix that #4093's review caught (same pattern: bare |
…o slash The original regex required `/` or end-of-string right after the mount name, so a link like `/commands?group=cluster` (no trailing slash before the query) silently passed through unchecked -- this tool's own blind spot, found the hard way: human review caught it by hand on DOC-7104 PR #4093, and the identical instances recurred in #4094/#4096/#4098 before this fix existed to catch them. Also reconsiders the `/commands` special case: it has no backing _index.md on disk, so _find_content_file always reports it unresolvable, but Hugo auto-generates a section page for the directory and GetPage finds it anyway (confirmed by building both /commands?group=x and /content/commands?group=x and comparing rendered hrefs -- identical). Review wanted the canonical form applied there too, so it's now hardcoded as FIXABLE instead of silently skipped. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…w pattern as #4094) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Fixed. Also swept for and fixed the same defect class elsewhere (7.22/7.8/8.0 references, plus the live tree via #4103). |
…r hooks Converts relref link shortcodes and note/tip/warning/alert callout shortcodes to render-hook equivalents across content/operate/rs/7.4/, excluding references/ (done separately in #4094) -- 145 of 162 files, 936 relref links and 155 callouts. Found and fixed the recurring indented-callout bug (27 files, ~30 blocks) and the recurring HGETALL missing-paren relref in databases/connect/troubleshooting-guide.md (3rd version to carry it: live tree, 7.22, now 7.4). Flagged, not fixed: 6 pre-existing broken relref targets in new-features-redis-enterprise.md (draft: true, never renders) -- same 6 targets that recur in every version. Review (round 2) caught three more issues, all fixed -- same as #4095: - Bare /commands links in _index.md and security/access-control/redis-acl-overview.md, missing the /content/ prefix (confirmed identical rendered href either way). - new-features-redis-enterprise.md's 6 dead links: applied the same /content/ prefix for consistency. Cosmetic only -- none of the 6 targets exist regardless of prefix. - databases/import-export/flush.md: the port-configurations link's anchor was a stray old absolute URL concatenated into the fragment, predating this migration. Replaced with the real heading slug. Verified via build/diff_rendered_hrefs.py: after filtering the known CSS-asset-fingerprint noise from comparing builds in two different worktree environments, the only real content change is the corrected flush.md anchor -- everything else confirmed 0 diff. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
migrate_shortcode_links.py's linkify stage correctly canonicalizes almost every converted link to /content/<path>.md[#anchor], but a link that gets a manual post-hoc text fix after the pipeline already ran (e.g. inserting a separator slash a relref-plus-literal-suffix concatenation was missing) never gets a second pass through linkify. The result is a bare /operate/... path that resolves to the exact same rendered href as the canonical form, so build/diff_rendered_hrefs.py -- this migration's usual verification -- is blind to it by construction. Found on PR #4086 (release-notes/ unit): human review manually flagged 8 malformed links; a corpus-wide grep for the same shape found 21 across 9 files (13 more than manual review caught), plus 8 more that turned out to be genuinely pre-existing dead links in the identical shape, invisible to any prior check since Hugo's relref shortcode only ever validated its own target, never text concatenated onto it afterward. check_uncanonicalized_links.py reuses migrate_shortcode_links.py's own resolver (_find_content_file) so a --fix run applies the exact same rewrite the pipeline would have. Three outcomes: FIXABLE (resolves, --fix rewrites it), MOUNT_ONLY (resolves only through a Hugo module mount -- never auto-fixed, same rationale _find_content_file already documents for not following mounts on a rewrite), DEAD (doesn't resolve at all -- reported only, never guessed). A second commit fixed the tool's own blind spot, found immediately on its first real use: the original MOUNT_PREFIX_RX required a `/` or end-of-string right after the mount name, so a bare `?query`/`#fragment` with no slash before it (e.g. /commands?group=x) silently passed through unchecked -- exactly the shape human review caught by hand across DOC-7104 PR #4093/#4094/#4096/#4098. Also reconsidered the `/commands` special case: it has no backing _index.md on disk so the filesystem resolver always calls it unresolvable, but Hugo auto-generates a section page for the directory and GetPage finds it anyway (confirmed by building both /commands?group=x and /content/commands?group=x and diffing rendered hrefs -- identical). Now hardcoded as FIXABLE instead of silently skipped. Verified against the pre-fix state of PR #4086: reproduces the exact 21 FIXABLE / 8 DEAD split. A full-corpus scan of content/ elsewhere comes back to 3 unrelated hits, confirming it isn't noisy. 8 unit tests cover both commits' behavior. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Summary
Unit 10 of 15 in the DOC-7104 shortcode-to-render-hook migration: converts every file under
content/operate/rs/7.4/references/(includingrest-api/) from{{< relref >}}and{{< note >}}/{{< warning >}}shortcodes to plain Markdown links and> [!NOTE]/> [!WARNING]blockquotes resolved by the DOC-6909 render hooks (layouts/_default/_markup/render-link.htmlandrender-blockquote.html).The
rest-api/subtree (169 of the 246 files) is explicitly in scope per the ticket: this frozen 7.4 snapshot was generated once and never regenerated, so a one-time conversion is safe and permanent.content/operate/rs/7.4/references/relrefshortcodes across 165 files; 20 callouts (16note, 4warning, 0tip/info/alert) across 16 files; 14 files carried both.cli-utilities/rladmin/_index.mdhad a{{<note>}}indented inside a numbered list item, with only the header line indented by the converter and the continuation/closing lines left flush left, plus a stray whitespace-only>artifact line. Re-indented all blockquote lines to match the list item and dropped the stray line. Verified via rendered HTML (before vs. after) that the<li>nesting is unchanged.cli-utilities/redis-cli/_index.mdline 153 has a markdown link with a relref shortcode but no closing)— confirmed viagit show HEADthat this was already broken before this migration. Left unconverted per "a missed rewrite is fine, a wrong one is not."Verification
hugo --minifycurrently fails site-wide on an unrelated pre-existing esbuild error on/commands/cf.reserve, confirmed pre-existing in unit 8).build/diff_rendered_hrefs.py(patched version fromDOC-7104-diff-hrefs-fix, used for verification only and not included in this diff) scoped tooperate/rs/7.4/references: 244/244 pages compared, 0 href-set changes.build/diff_rendered_hrefs.pycarries no changes in this PR's diff.Test plan
cli-utilities/rladmin/_index.mdand therest-api/callout pages) render correctlycli-utilities/redis-cli/_index.mdis tracked separately if it needs a fix🤖 Generated with Claude Code
Note
Low Risk
Documentation-only mechanical conversion of links and callouts in a static 7.4 snapshot; no runtime or security impact.
Overview
Migrates the frozen Redis Enterprise 7.4 references tree (CLI utilities, compatibility tables, metrics, REST API docs, and related pages) off Hugo shortcodes so render hooks can resolve links and callouts.
Internal links:
{{< relref "..." >}}is replaced with plain Markdown targets under/content/...(including_index.md,.md, and hash anchors). The change is broad—crdb-cli,rladmin,redis-cli, command-compatibility matrices, and cross-links to RS/RC/develop/commands content all follow the same pattern.Callouts:
{{< note >}}/{{< warning >}}become> [!NOTE]and> [!WARNING]blockquotes (e.g. internal CLI utilities warning,rladminshell note, RESP3 notes, REST API warnings).No product behavior or API semantics change; this is documentation markup only, aligned with the DOC-7104 shortcode-to-render-hook migration for this directory.
Reviewed by Cursor Bugbot for commit aaf1b78. Bugbot is set up for automated code reviews on this repo. Configure here.